Reproducible Research

Overview

History of reproducible research

Gavish & Gonoho AAAS 2011, Oxberry 2013

Motivations:
Claerbout’s principle

“An article about computational result is advertising, not scholarship. The actual scholarship is the full software environment, code and data, that produced the result.”
Claerbout and Karrenbach, Proceedings of the 62nd Annual International Meeting of the Society of Exploration Geophysics. 1992

Benefits are straightforward

But limitations are substantial

Technical

Cultural & personal

Our work exists on a spectrum of reproducibility

alt text

Peng 2011, Science 334(6060) pp. 1226-1227

Goal: expose more of the research workflow

alt text

http://www.stodden.net/AMP2011/slides/pengslides.pdf

Common practices of many scientists

  1. Enter data in Excel
  2. Use Excel for data cleaning & descriptive statistics
  3. Use ArcGIS and use point-and-click options for processing and visualization
  4. Import data into SPSS/SAS/Stata for further analysis
  5. Use point-and-click options to run statistical analyses
  6. Copy & paste output to Word document, repeatedly

alt text

Common practices of many scientists

alt text

Click trails are ephemeral & dangerous

alt text

Case study: Reinhart and Rogoff controversy

alt text

alt text

Excel coding error sliced several countries out of the data set…. The Economist

Case study: Gay Marrage

In May 2015 Science retracted a study of how canvassers can sway people’s opinions about gay marriage published just 5 months ago.

- Science Editor-in-Chief Marcia McNutt

Two Berkeley grad students who attempted to replicate the study quickly discovered that the data must have been faked.

Source

Case study: Seizure Medicine

2013 Seizure study retracted after authors realize data got “terribly mixed”

“The article has been retracted at the request of the authors. After carefully re-examining the data presented in the article, they identified that data of two different hospitals got terribly mixed. The published results cannot be reproduced in accordance with scientific and clinical correctness.”" Authors of Low Dose Lidocaine for Refractory Seizures in Preterm Neonates

Source

Bad spreadsheet merge kills depression paper, quick fix resurrects it

Authors informed the journal that the merge of lab results and other survey data used in the paper resulted in an error regarding the identification codes. Results of the analyses were based on the data set in which this error occurred.

Lower levels of CSF IL-6 were associated with current depression and with future depression […]” Original conclusion

Higher levels of CSF IL-6 and IL-8 were associated with current depression […]” Revised conclusion

Source

Scripted analyses are superior

alt text

Literate statistical programming

“Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to humans what we want the computer to do.” Donald E. Knuth, Literate Programming, 1984

For example… Let’s calculate the current time in R.

time <- format(Sys.time(), "%a %d %b %X %Y")

The text and R code are interwoven in the output:

The time is `r time`

The time is Mon 16 Oct 18:21:28 2017

Literate programming: for and against

For

Against

Reproducible Research in R

Need a programming language

The machine-readable part: R

alt text

“both a container for the different elements that make up the document and its computations (i.e. text, code, data, etc.), and as a means for distributing, managing and updating the collection… allow us to move from an era of advertisement to one where our scholarship itself is published” Gentleman and Temple Lang 2004

Need a document formatting language

alt text

Markdown: lightweight document formatting syntax. Easy to write, read and publish as-is.

The human-readable part

rmarkdown: - minor extensions to allow R code display and execution - embed images in html files (convenient for sharing) - equations - * for bullet, _ for underline

Dynamic documents in R

knitr - descendant of Sweave

Engine for dynamic report generation in R

alt text


Pandoc: document converter

alt text http://kieranhealy.org/blog/archives/2014/01/23/plain-text/

A universal document converter, open source, cross-platform

Version Control

Tracking changes with version control

Payoffs

Costs - Learning curve

alt text alt text alt text

Environment for reproducible research

alt text

RStudio ‘projects’ make version control & document preparation simple

Depositing code and data

Payoffs - Free space for hosting (and paid options) - Assignment of persistent DOIs - Tracking citation metrics

Costs - Sometimes license restrictions (CC-BY & CC0) - Limited or no private storage space

alt text alt text alt text

A hierarchy of reproducibility

alt text Stodden (IASSIST 2010) sampled American academics registered at the Machine Learning conference NIPS (134 responses from 593 requests (23%). Red = communitarian norms, Blue = private incentives

alt text Stodden (IASSIST 2010) sampled American academics registered at the Machine Learning conference NIPS (134 responses from 593 requests (23%). Red = communitarian norms, Blue = private incentives

Standards to normalise reproducible research

Reproducible Research Standard (Stodden 2009)

Biggest challenge: culture change

Promote culture change through positive attribution

Implement mechanisms to indicate & encourage degrees of compliance (ie. clear definitions for different levels of reproducibility), cf. Stodden’s:

Our role in the future of reproducible research (Leveque et al 2012)

Demo: let’s get started

R Markdown

Cheatsheet:

alt text

https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf

Create new file

File -> New File -> RMarkdown -> Document -> HTML

alt text

Step 1: Load packages

All R code to be run must be in a code chunk like this:

#```{r,eval=F}
CODE HERE
#```

Load these packages in a code chunk (you may need to install some packages):

library(dplyr)
## Warning: package 'dplyr' was built under R version 3.4.2
library(ggplot2)
library(maps)
library(spocc)

Do you think you should put install.packages() calls in your script?

Step 2: Load data

Now use the occ() function to download all the occurrence records for the American robin (Turdus migratorius) from the Global Biodiversity Information Facility.

alt text

Licensed under CC BY-SA 3.0 via Wikimedia Commons

## define which species to query
sp='Turdus migratorius'

## run the query and convert to data.frame()
d = occ(query=sp, from='ebird',limit = 1000) %>% occ2df()

This can take a few seconds.

Step 3: Map it

# Load coastline
map=map_data("world")

ggplot(d,aes(x=longitude,y=latitude))+
  geom_polygon(aes(x=long,y=lat,group=group,order=order),data=map)+
  geom_point(col="red")+
  coord_equal()
## Warning: Ignoring unknown aesthetics: order

Step 4:

Update the YAML header to keep the markdown file

From this:

title: "Untitled"
author: "Adam M. Wilson"
date: "October 31, 2016"
output: html_document

To this:

title: "Demo"
author: "Adam M. Wilson"
date: "October 31, 2016"
output: 
  html_document:
      keep_md: true

And click knit HTML to generate the output

Step 5: Explore markdown functions

  1. Use the Cheatsheet to add sections and some example narrative.
  2. Try changing changing the species name to your favorite species and re-run the report.
  3. Add more figures or different versions of a figure
  4. Check out the kable() function for tables (e.g. kable(head(d)))

alt text

Final

Abandoning the habit of secrecy in favor of process transparency and peer review was the crucial step by which alchemy became chemistry.Raymond, E. S., 2004, The art of UNIX programming: Addison-Wesley.

Colophon

References

See Rmd file for full references and sources